#!/bin/env python
# -*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

u"""
Interfaces thread/process
"""

__all__ = [u'IProcessHandler', u'ILock']

import time
from traits.api import Interface


from _pylot.minimal.path import Path
from _pylot.minimal.utils import check_type, error
from _pylot.minimal.commands import ShellCommand, PythonCommand
from _pylot.minimal.commandgroup import CommandGroup

from _pylot.minimal.interfaces.i_iohandler import IIOHandler


class ILock (Interface):
  u"""
  Primitive Lock object.
  ILock API is inspired by 
  `thread.Lock<http://docs.python.org/library/threading.html#lock-objects>`_
  standard python object.

  A primitive lock is in one of two states, "locked" or "unlocked". 
  It is created in the unlocked state. 
  It has two basic methods, acquire() and release(). 
  When the state is unlocked, acquire() changes the state to locked and returns 
  immediately. When the state is locked, acquire() blocks until a call to 
  release() in another thread changes it to unlocked, then the acquire() 
  call resets it to locked and returns.
  """
  def acquire (self):
    pass

  def release (self):
    pass


class IProcessHandler (Interface):
  u"""
  Class used to run shell commands and python threads.
  
  Threads and commands are stored in a :class:`~_pylot.minimal.CommandGroup` 
  class. 
  This group can next be run by IProcessHandler, see
  :meth:`~_pylot.minimal.IProcessHandler.run` and 
  :meth:`~_pylot.minimal.IProcessHandler.runCmd`
  
  IProcessHandler provides properties to customise outputs and runs 

  You can change maximum of simultaneous process with max_process property.
  Value must be an integer. This property has no effect if wait=True.
  """
  wait = True
  max_process = 3

  def __init__(self, wait=True, max_process=3) :
    u"""
    wait: bool
    max_process: int
    """
    pass


  def getRunningProcess(self):
    u"""
    """

  def getInQueueProcess(self):
    u"""
    """

  def run(self, command_group, wait=None):
    u"""
    :param command_group: command group you want to run
    :type command_group: :class:`~_pylot.minimal.CommandGroup`
    :param wait: wait command_group run finish, [default: use ProcessHandler value]
    :type wait: bool or None
    """

  def runCmd(self, cmd, args=[], cmd_id=None, alias=None,
             working_directory=None, wait=None):
    u"""
    Create a CommandGroup object with only one ShellCommand and run it
    """

  def runPython(self, python_method, args=[], kargs={}, cmd_id=None, alias=None,
                working_directory=None, wait=None):
    u"""
    Create a CommandGroup object with only one PythonCommand and run it
    """

  def newLock (self):
    u"""
    Return a lock object implementing ILock
    """

  def clearQueueProcess(self):
    u"""
    """

  def killAllProcess(self):
    u"""
    """

  def requireGroups(self, groups, timeout=None):
    u"""
    Define required groups.
    IProcessHandler is locked until all required groups executions are not 
    successfully finished. If a required fails, IProcessHandler is unlocked
    and an error message is sent.
    
    :param args: one or more command groups
    :type args: CommandGroup
    """

